Skip to main content

Flutter SDK 插件

Flutter SDK 插件同时具备 无埋点SDK 和 埋点SDK 功能，但是在使用 Flutter 无埋点功能前需要按照 Flutter Aspect 集成 才能使无埋点功能生效。

环境配置​

info

Growingio Flutter SDK 插件集成​

添加依赖​

以工程flutter_app为例，在pubspec.yaml文件中添加依赖。

dependencies:
  growingio_flutter_plugin: '4.0.0'

然后执行 flutter pub get 指令安装插件。

点击查看 GrowingIO Flutter 插件和 SDK 版本的依赖关系
Flutter 插件版本Android SDK 版本范围Apple SDK 版本范围
>= v1.1.3>= v3.5.0>= v3.5.0
= v2.0.0>= v4.1.0>= v4.1.0
原生+Flutter

若是纯 Flutter 应用，上述集成就可以使用了。若是项目中同时具有原生代码和Flutter，且原生也需要支持无埋点功能，那么就需要基于无埋点初始化配置集成原生的SDK。 Flutter和原生共用一套SDK逻辑，不会初始化两次。

在Android中， Gradle Plugin 若出现 'no growingio autotracker sdk dependency was found' 的编译错误，可以将插件的配置项 skipDependencyCheck 设置为true。

Flutter 插件初始化​

GrowingIO Flutter SDK 支持在 Flutter 中初始化 SDK，也同时支持在原生代码中初始化。如果需要更多的功能设置，我们更推荐您在原生端实现初始化。

原生端初始化​

原生端初始化请参考各端的初始化文档：

Flutter 初始化​

在 Flutter 端进行初始化，请将 SDK 的初始化代码放入 main.dart 的 main 中，代码示例如下：


void main() async {
  ...
  WidgetsFlutterBinding.ensureInitialized();
  GrowingAutotracker.startWithConfiguration(
    projectId: "Your ProjectId",
    dataCollectionServerHost: "Your collection server host",
    dataSourceId: "Your datasourceid",
    urlScheme: "Yoour Url Scheme",
    debugEnabled: true,
    modules: {
      AdvertLibraryGioModule(config: AdvertConfig()),
    },
    dataCollectionEnabled: true,
    autoTrackAllRoutePage: false,
    idMappingEnabled: true,
    cellularDataLimit: 10,
    dataUploadInterval: 15,
    sessionInterval: 20,
  );
  ...
  runApp(MyApp());
}

初始化配置说明​

在 Flutter 初始化中会传入各式的参数，参数配置如下表所示：

配置项参数类型是否必填默认值说明版本
projectIdString是null项目ID，每个应用对应唯一值-
urlSchemeString是nullAndroid 应用特有的URLScheme，用于外部应用拉起应用，如圈选-
dataSourceIdString是null应用的DataSourceId，唯一值-
dataCollectionServerHostString是null服务端部署后的 ServerHost-
autoTrackAllRoutePagebool否false是否自动开启页面采集，无埋点独有>=4.1.0
channelString否null应用的分发渠道-
debugEnabledbool否false调试模式，会打印SDK log，抛出错误异常，在线上环境请关闭-
cellularDataLimitint否10每天发送数据的流量限制，单位MB-
dataUploadIntervalint否15数据发送的间隔，单位秒-
sessionIntervalint否30会话后台留存时长，单位秒-
dataCollectionEnabledbool否true是否采集数据-
requestTimeoutint否30设置数据上报请求的超时时间，单位秒-
androidIdEnabledbool否false是否在 Android 设备上采集 AndroidId-
imeiEnabledbool否false是否在 Android 设备上采集 imei-
modulesSet<LibraryGioModule>否empty模块集成，具体请阅读下方的模块说明-

urlScheme 说明​

在使用 GrowingIO SDK 的Mobile Debugger 和圈选功能时，需要外部浏览器通过扫描二维码来拉起应用。

模块配置​

GrowingIO SDK 利用模块来实现SDK核心功能以外的额外功能，在 Flutter SDK 插件中，可以通过在 modules 传入模块声明来开启相应的功能。

目前 Flutter SDK 可启用的模块功能包括：

广告功能​

GrowingTracker.startWithConfiguration(
    //....
    modules: {
      AdvertLibraryGioModule(
        config: AdvertConfig(readClipBoardEnable: true, /// 是否打开剪切板
          deepLinkHost: "Your deepLinkHost", /// 深度链接配置地址, SaaS取默认值 “https://link.growingio.com”
          asaEnabled: true, /// 仅iOS端使用
          deepLinkCallback:(Map<String,String> params,int error,int time){
            ///监听深度链接中的地址参数
          },
      )),
    },
    //....
  );

广告模块包括激活事件和深度链接，能帮助客户提供广告，活动的引导跳转和下载。

info

在 Flutter SDK 启动广告模块同时，原生端（包括Android和iOS端）都需要引入相应的模块代码，请参考：

加密模块​

GrowingTracker.startWithConfiguration(
    //....
    modules: {
      EncoderLibraryGioModule(),
    },
    //....
  );

加密模块用于数据网络上传数据的加密。

Json 模块​

GrowingTracker.startWithConfiguration(
    //....
    modules: {
      JsonLibraryModule(),
    },
    //....
  );

Json 数据模块将会使用 Json 格式保存和上传事件数据。

H5混合模块​

GrowingTracker.startWithConfiguration(
    //....
    modules: {
      HybridLibraryGioModule(),
    },
    //....
  );

若使用了原生的WebView,且内嵌 H5 页面如果也需要进行数据采集（H5 页面已经集成 Web JS SDK），则可以开启该 H5混合模块。

info

在 Flutter SDK 启动H5混合模块同时，原生端（包括Android和iOS端）都需要引入相应的模块代码，请参考：

API说明​

GrowingAutotracker.get().setDataCollectionEnabled(true)
GrowingAutotracker.get().setLoginUserId(userId: "cpacm",userKey: "name")
GrowingAutotracker.get().cleanLoginUserId()
GrowingAutotracker.get().setLoginUserAttributes(attributes: {"sex":"female"});
GrowingAutotracker.get().setLocation(latitude: 20.11,longitude: 20.11)
GrowingAutotracker.get().cleanLocation()
GrowingAutotracker.get().getDeviceId()
GrowingAutotracker.get().trackCustomEvent(eventName: "eventName", attributes: {"age":"18"})
String? timerId =await GrowingAutotracker.get().trackTimerStart(eventName: "custom");
GrowingAutotracker.get().trackTimerPause(timerId: timerId!);
GrowingAutotracker.get().trackTimerResume(timerId: timerId);
GrowingAutotracker.get().trackTimerEnd(timerId: timerId,attributes: {});
GrowingAutotracker.get().removeTimer(timerId: timerId);
GrowingAutotracker.get().clearTrackTimer();
GrowingAutotracker.get().setGeneralProps(props:{});
GrowingAutotracker.get().removeGeneralProps(keys:["col1 row1", "key1"]);
GrowingAutotracker.get().clearGeneralProps();

GrowingAutotracker.get().registerComponent(module);

1. 数据采集开关​

setDataCollectionEnabled
打开或关闭数据采集

参数说明​

参数参数类型说明
enabledbooleantrue打开数据采集，false关闭数据采集，默认 true

示例​

GrowingAutotracker.get().setDataCollectionEnabled(true);

2. 设置登录用户ID​

setLoginUserId
当用户登录之后调用，设置登录用户ID

info

  • 如果您的App每次用户升级版本时无需重新登录的话，为防止用户本地缓存被清除导致的无法被识别为登录用户，建议在用户每次升级App版本后初次访问时重新调用setLoginUserId方法

  • 当需要标记用户ID类型时，请先进行规划，并在平台的数据中心，添加新的用户身份类型，再设置userkey，误设会影响数据质量。 同时在初始化 SDK 时设置idMappingEnabled为true

参数说明​

参数参数类型说明
userIdString长度限制大于0且小于等于1000，如果大于长度1000将只截取前1000长度
userKeyString适用于ID-MAPPING,可设置 userId 的类型,可选填

示例​

GrowingAutotracker.get().setLoginUserId(userId: "cpacm",userKey: "name");

3. 清除登录用户ID​

cleanLoginUserId
当用户登出之后调用，清除已经设置的登录用户ID。

示例​

GrowingAutotracker.get().cleanLoginUserId();

4. 设置用户的地理位置​

setLocation
设置用户当前的地理位置，基于WGS-84坐标

参数说明​

参数参数类型说明
latitudedouble地理坐标点纬度
longitudedouble地理坐标点经度

示例​

GrowingAutotracker.get().setLocation(latitude: 20.11,longitude: 20.11);

5. 清除用户的地理位置​

cleanLocation
清除用户当前的地理位置

示例​

GrowingAutotracker.get().cleanLocation();

6. 设置登录用户属性​

setLoginUserAttributes
发送登录用户属性事件，用于用户信息相关分析； 在添加发送用户属性事件代码之前，需在CDP平台用户管理界面创建用户属性。

参数说明​

参数参数类型说明
attributesMap<String, String>用户属性信息

示例​

GrowingAutotracker.get().setLoginUserAttributes(attributes: {"sex":"female"});

7. 设置埋点事件​

trackCustomEvent
发送一个埋点事件；注意：在添加发送的埋点事件代码之前，需在CDP平台事件管理界面创建埋点事件以及关联事件属性；
如果事件属性需关联维度表，请在事件属性下关联维度表（ CDP平台版本>= 2.1 ）

参数说明​

参数参数类型说明
eventNameString事件名，事件标识符
attributesMap<String, String>事件发生时所伴随的属性信息；当事件属性关联有维度表时，属性值为对应的维度表模型ID(记录ID)（可选）

示例​

GrowingAutotracker.get().trackCustomEvent(eventName: "custom",attributes: {"item":"exp"});

8. 获取设备ID​

getDeviceId
获取设备ID，又称为匿名用户ID，SDK 自动生成用来定义唯一设备。 如果没有初始化SDK 或者关闭采集开关可能返回值为null，且可能有IO操作。

示例​

GrowingAutotracker.get().getDeviceId();

9. 事件化计时器​

trackTimerStart
初始化一个事件计时器，参数为计时事件的事件名称，返回值为该事件计时器唯一标识

trackTimerPause
暂停事件计时器，参数为trackTimerStart返回的唯一标识

trackTimerResume
恢复事件计时器，参数为trackTimerStart返回的唯一标识

trackTimerEnd
停止事件计时器，参数为trackTimerStart返回的唯一标识。调用该接口会自动触发删除定时器。

removeTimer
删除事件计时器，参数为 trackTimerStart 返回的唯一标识。
该接口会将标识为 timerId 的计时器置为空。调用停止计时器接口，会自动触发该接口。注意移除时不论计时器处于什么状态，都不会发送事件。

clearTrackTimer
清除所有已经注册的事件计时器。
存在所有计时器需要清除时调用。注意移除时不论计时器处于什么状态，都不会发送事件。

参数说明​

参数参数类型说明
eventNameString事件名称，事件标识符
attributesMap<String, String>事件发生时所伴随的属性信息

返回值说明​

参数参数类型说明
timerIdString计时器唯一标识

示例​

String? timerId =await GrowingAutotracker.get().trackTimerStart(eventName: "custom");
GrowingAutotracker.get().trackTimerPause(timerId: timerId!);
GrowingAutotracker.get().trackTimerResume(timerId: timerId);
GrowingAutotracker.get().trackTimerEnd(timerId: timerId,attributes: {});
GrowingAutotracker.get().removeTimer(timerId: timerId);
GrowingAutotracker.get().clearTrackTimer();

10. 通用属性​

setGeneralProps({required Map<String, dynamic> props})
为所有的自定义事件（CustomEvent）添加通用属性。

removeGeneralProps({required List<String> keys})
根据Key值移除已经设置的属性，如不存在则不影响。

clearGeneralProps()
清除所有已经设置的通用属性。

GrowingAutotracker.get().setGeneralProps(props:{"key1":"name"});
GrowingAutotracker.get().removeGeneralProps(keys:["xxx", "key1"]);
GrowingAutotracker.get().clearGeneralProps();

11. 注册模块组件​

registerComponent
可通过该方法手动注册SDK需要的可配置模块组件（推荐在初始化通过 Configuration 初始化时注册）。

参数说明​

参数参数类型说明
moduleLibraryGioModule模块
configConfiguration模块的配置类(可选参数)

示例​

GrowingAutotracker.get().registerComponent(JsonLibraryModule());

12. 无埋点页面事件​

Flutter的 Page事件不再基于 Router，而是用开发者通过 mixin 类 GrowingPageStateMixin 或者 GrowingPageStatelessMixin 来实现。

  1. 在 StatefulWidget 中，可以将其 State 声明为 Page页面，如下：
class _HomeScreenState extends State<HomeScreen> with GrowingPageStateMixin {
  @override
  String get alias => "HomeScreen";

  @override
  Map<String, dynamic>? get attributes => {};
}
  1. 在 StatelessWidget 中，直接将自己声明为 Page 页面，如下：
class SplashScreen extends StatelessWidget with GrowingPageStatelessMixin {
  @override
  String get alias => "SplashScreen";

  @override
  Map<String, dynamic>? get attributes => {};
}

alias 对应页面的名称，attributes为页面属性。

另外，可以直接在 Page 下调用 trackCustomEvent 方法，发送的自定义事件就会携带事件属性，如不需要则可以调用GrowingAutotracker.get().trackCustomEvent.